The Arsenal Files 8

home *** CD-ROM | disk | FTP | other *** search

/ The Arsenal Files 8 / The Arsenal Files Collection #8 (Arsenal Computer) (1996).ISO / prg_casm / recio215.zip / SPEC.TXT < prev next >

Wrap

Text File | 1996-10-26 | 97KB | 3,179 lines

Title: SPECIFICATION OF C LANGUAGE RECIO LIBRARY Copyright: (C) 1994-1996, William Pierpoint Version: 2.15 Date: October 26, 1996 1.0 RECORD INPUT/OUTPUT <recio.h> 1.1 Introduction The header <recio.h> declares two types, several macros, and many functions for performing line oriented input and output. 1.1.1 Record Streams Input and output are mapped into logical data record streams. A record stream is an ordered sequence of characters composed into records, each record consisting of zero or more characters plus a terminating record delimiter character. The terminating record delimiter for a file is the newline character. Each record consists of zero or more fields. The record may be broken into fields in two different ways: (1) character delimited and (2) column delimited. For character delimited fields, each field consists of zero or more characters plus a terminating field delimiter character or, for the last field in the record, the record delimiter character. For column delimited fields, each field consists of one or more characters delimited by a single column position for fields consisting of one character, or by beginning and ending column positions for fields consisting of one or more characters. Four types of fields are defined: (1) character, (2) text, (3) numeric, and (4) time. A character field consists of a single character. A text field consists of a sequence of zero or more characters delimited at each end by an optional text delimiter character. A numeric field consists of a sequence of one or more characters from the set of valid characters for the number type (integral or floating point) and radix. A time field consists of a sequence of one or more characters from the set of valid characters for the time type, delimited according to a specified format string. 1.1.2 Types The types are REC which is an object type capable of recording all information needed to control a record stream used for line oriented input or output, including its file pointer, pointers to its associated record and field buffers, field and text delimiting characters, an error indicator that records whether an error has occurred, and an end-of-file indicator that records whether the end of the file has been reached; and rpos_t which is an object type capable of recording all the information needed to specify uniquely any field position within a record. 1.1.3 Macros The macros are RECBUFSIZ FLDBUFSIZ which expand to integral constant expressions, which are the initial sizes of the record buffer and the field buffer; RECFLDCH RECTXTCH which expand to integral constant expressions, which are the default values of the characters used to separate the fields and delimit text in a record and whose default value shall correspond to the value of the space character; RECBEGYR which expands to an integral constant expression, which is the default 4-digit value for the beginning year corresponding to the beginning year of the 2-digit time format; ROPEN_MAX which expands to an integral constant expression that is the maximum number of files that can be open simultaneously; RECIN RECOUT RECERR which expand to an integral constant expression that is the context number for the recin record stream that gets input from the <stdio.h> standard input stream stdin, the recout record stream that puts output to the <stdio.h> standard output stream stdout, and the recerr record stream that puts output to the <stdio.h> standard error stream stderr. 1.1.4 Expressions The expressions are recin recout recerr which are of type "pointer to REC" that points to the REC object associated with the <stdio.h> FILE objects stdin (standard input stream), stdout (standard output stream), and stderr (standard error stream). The recin, recout, and recerr record streams are always open and are included in the count of ROPEN_MAX. 1.2 Record Access Functions 1.2.1 The rclose Function Synopsis #include <recio.h> void rclose(REC *rp); Description The rclose function causes the record stream pointed to by rp and the associated file to be closed. Any unread data is discarded. The record stream is disassociated from the file. If associated buffers were automatically allocated, they are deallocated. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rclose function returns no value. 1.2.2 The rcloseall Function Synopsis #include <recio.h> int rcloseall(void); Description The rcloseall function causes all the open record streams, and all the files associated with the open record streams, to be closed. Any unread data is discarded. Each record stream is disassociated from its file. If associated buffers were automatically allocated, they are deallocated. Returns The rcloseall function returns the number of record streams successfully closed. 1.2.3 The ropen Function Synopsis #include <recio.h> REC *ropen(const char *filename, const char *mode); Description The ropen function opens the file whose name is the string pointed to by filename, and associates a record stream with it. The argument mode points to a string whose first letter is: "r" - open text file for input "w" - open text file for output "a" - open text file for append When successfully opened, the error and end-of-file indicators for the record stream are clear. If an error occurs, errno is set to one of the error reporting macros as defined in <errno.h>, the callback error function is called (except when the file associated with filename is not able to be opened), and a null pointer is returned. Returns The ropen function returns a pointer to the object controlling the record stream. If the open operation fails, ropen returns a null pointer. 1.2.4 The rsetfldsiz Function Synopsis #include <recio.h> void rsetfldsiz(REC *rp, size_t fldsize); Description The rsetfldsiz function reallocates the field buffer associated with the record stream pointed to by rp to the new size of fldsize. The rsetfldsiz function may be used only after the record stream pointed to by rp has been opened and before any data is read into the record buffer. Data is read into the record buffer by the function rgetrec, or by calling a function that either skips a field or gets data from a field. If rsetfldsiz is not used, the initial size of the field buffer is set by the value of the macro FLDBUFSIZ. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rsetfldsiz function returns no value. 1.2.5 The rsetrecsiz Function Synopsis #include <recio.h> void rsetrecsiz(REC *rp, size_t recsize); Description The rsetrecsiz function reallocates the record buffer associated with the record stream pointed to by rp to the new size of recsize. The rsetrecsiz function may be used only after the record stream pointed to by rp has been opened and before any data is read into the record buffer. Data is read into the record buffer by the function rgetrec, or by calling a function that either skips a field or gets data from a field. If rsetrecsiz is not used, the initial size of the field buffer is set by the value of the macro RECBUFSIZ. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rsetrecsiz function returns no value. 1.3 Character Delimited Field Input Functions The character delimited field input functions use a character (such as a comma or space) to determine where each field begins and ends. 1.3.1 The rbgeti Function Synopsis #include <recio.h> int rbgeti(REC *rp, int base); Description The rbgeti function reads a field consisting of one integral number represented by the radix determined by the value of base from the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. Base may be zero or in the range of 2 to 36 inclusive. If the value of base is zero, the expected form of the integral number is described by section 3.1.3.2 of ANSI X3.159-1989. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero. Returns The rbgeti function returns a signed integer from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rbgeti returns zero. If the record stream is at end-of-file (end-of-file indicator set), rbgeti returns zero. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rbgeti returns zero. 1.3.2 The rbgetl Function Synopsis #include <recio.h> long rbgetl(REC *rp, int base); Description The rbgetl function reads a field consisting of one integral number represented by the radix determined by the value of base from the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. Base may be zero or in the range of 2 to 36 inclusive. If the value of base is zero, the expected form of the integral number is described by section 3.1.3.2 of ANSI X3.159-1989. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero (0L). Returns The rbgetl function returns a signed long from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rbgetl returns zero (0L). If the record stream is at end-of-file (end-of-file indicator set), rbgetl returns zero (0L). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rbgetl returns zero (0L). 1.3.3 The rbgetui Function Synopsis #include <recio.h> unsigned int rbgetui(REC *rp, int base); Description The rbgetui function reads a field consisting of one non-negative integral number represented by the radix determined by the value of base from the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. Base may be zero or in the range of 2 to 36 inclusive. If the value of base is zero, the expected form of the integral number is described by section 3.1.3.2 of ANSI X3.159-1989. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero. Returns The rbgetui function returns an unsigned integer from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rbgetui returns zero. If the record stream is at end-of-file (end-of-file indicator set), rbgetui returns zero. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rbgetui returns zero. 1.3.4 The rbgetul Function Synopsis #include <recio.h> unsigned long rbgetul(REC *rp, int base); Description The rbgetul function reads a field consisting of one non-negative integral number represented by the radix determined by the value of base from the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. Base may be zero or in the range of 2 to 36 inclusive. If the value of base is zero, the expected form of the integral number is described by section 3.1.3.2 of ANSI X3.159-1989. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero (0L). Returns The rbgetul function returns an unsigned long from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rbgetul returns zero (0L). If the record stream is at end-of-file (end-of-file indicator set), rbgetul returns zero (0L). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rbgetul returns zero (0L). 1.3.5 The rgetc Function Synopsis #include <recio.h> int rgetc(REC *rp); Description The rgetc function reads a field consisting of one non-white space character from the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns EOF. Returns The rgetc function returns a character from a single non-white space character field in the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, or if there is more than or less than one non-white character in the field, the error indicator for the record stream is set, and rgetc returns EOF. If the record stream is at end-of-file (end-of-file indicator set), rgetc returns EOF. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rgetc returns EOF. 1.3.6 The rgetd Function Synopsis #include <recio.h> double rgetd(REC *rp); Description The rgetd function reads a field consisting of one floating point number from the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero. Returns The rgetd function returns a double precision floating point number from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rgetd returns zero (0.0). If the record stream is at end-of-file (end-of-file indicator set), rgetd returns zero (0.0). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rgetd returns zero (0.0). 1.3.7 The rgetf Function Synopsis #include <recio.h> float rgetf(REC *rp); Description The rgetf function reads a field consisting of one floating point number from the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero. Returns The rgetf function returns a single precision floating point number from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rgetf returns zero (0.0). If the record stream is at end-of-file (end-of-file indicator set), rgetf returns zero (0.0). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rgetf returns zero (0.0). 1.3.8 The rgeti Function Synopsis #include <recio.h> int rgeti(REC *rp); Description The rgeti function reads a field consisting of one integral number from the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero. Returns The rgeti function returns a signed integer from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rgeti returns zero. If the record stream is at end-of-file (end-of-file indicator set), rgeti returns zero. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rgeti returns zero. 1.3.9 The rgetl Function Synopsis #include <recio.h> long rgetl(REC *rp); Description The rgetl function reads a field consisting of one integral number from the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero (0L). Returns The rgetl function returns a signed long from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rgetl returns zero (0L). If the record stream is at end-of-file (end-of-file indicator set), rgetl returns zero (0L). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rgetl returns zero (0L). 1.3.10 The rgets Function Synopsis #include <recio.h> char *rgets(REC *rp); Description The rgets function reads a field consisting of one text string from the input record stream pointed to by rp. Any leading white space before the text delimiter and any trailing white space after the text delimiter in the field is ignored. The text delimiters are not returned as part of the string. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns a pointer to an empty string. Returns The rgets function returns a pointer to a character array from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, the error indicator for the record stream is set, and rgets returns a pointer to an empty string. If the record stream is at end-of-file (end-of-file indicator set), rgets returns a pointer to an empty string. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rgets returns a pointer to an empty string. 1.3.11 The rgett Function Synopsis #include <recio.h> time_t rgett(REC *rp); Description The rgett function reads a field consisting of one time of type time_t from input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns (time_t)-1. Returns The rgett function returns a time of type time_t. If an attempt is made to read beyond the end-of-record, the error indicator for the record stream is set, and rgett returns (time_t)-1. If the record stream is at end-of-file (end-of-file indicator set), rgett returns (time_t)-1. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rgett returns (time_t)-1. 1.3.12 The rgettm Function Synopsis #include <recio.h> struct tm rgettm(REC *rp); Description The rgettm function reads a field consisting of one time of type struct tm from input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns an implementation defined value. Returns The rgettm function returns a time of type struct tm. If an attempt is made to read beyond the end-of-record, the error indicator for the record stream is set, and rgettm returns an implementation defined value. If the record stream is at end-of-file (end-of-file indicator set), rgettm returns an implementation defined value. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rgettm returns an implementation defined value. 1.3.13 The rgetui Function Synopsis #include <recio.h> unsigned int rgetui(REC *rp); Description The rgetui function reads a field consisting of one non-negative integral number from the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero. Returns The rgetui function returns an unsigned integer from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rgetui returns zero. If the record stream is at end-of-file (end-of-file indicator set), rgetui returns zero. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rgetui returns zero. 1.3.14 The rgetul Function Synopsis #include <recio.h> unsigned long rgetul(REC *rp); Description The rgetul function reads a field consisting of one non-negative integral number from the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero (0L). Returns The rgetul function returns an unsigned long from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rgetul returns zero (0L). If the record stream is at end-of-file (end-of-file indicator set), rgetul returns zero (0L). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rgetul returns zero (0L). 1.3.15 The rgotofld Function Synopsis #include <recio.h> void rgotofld(REC *rp, unsigned int num); Description The rgotofld function goes to the num number of the field for the record stream pointed to by rp. The first field in the record is number 1, the second field is number 2, etc. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rgotofld function returns no value. 1.3.16 The ristxtfld Function Synopsis #include <recio.h> unsigned ristxtfld(REC *rp); Description The ristxtfld function determines if the current field (the field most recently input or output) for the record stream pointed to by rp was quoted with the text delimiter character (provided the text delimiter character is not the space character). Returns The ristxtfld function returns non-zero if the current field was quoted and returns zero otherwise. If the text delimiter character for the stream is the space character, the ristxtfld function always returns zero. 1.3.17 The rnbgeti Function Synopsis #include <recio.h> int rnbgeti(REC *rp, unsigned int num, int base); Description The rnbgeti function reads a field consisting of one integral number represented by the radix determined by the value of base from field number num for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. The first field in a record is field number 1, the second field is field number 2, etc. Base may be zero or in the range of 2 to 36 inclusive. If the value of base is zero, the expected form of the integral number is described by section 3.1.3.2 of ANSI X3.159-1989. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero. Returns The rnbgeti function returns a signed integer from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rnbgeti returns zero. If the record stream is at end-of-file (end-of-file indicator set), rnbgeti returns zero. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rnbgeti returns zero. 1.3.18 The rnbgetl Function Synopsis #include <recio.h> long rnbgetl(REC *rp, unsigned int num, int base); Description The rnbgetl function reads a field consisting of one integral number represented by the radix determined by the value of base from field number num for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. The first field in a record is field number 1, the second field is field number 2, etc. Base may be zero or in the range of 2 to 36 inclusive. If the value of base is zero, the expected form of the integral number is described by section 3.1.3.2 of ANSI X3.159-1989. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero (0L). Returns The rnbgetl function returns a signed long from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rnbgetl returns zero (0L). If the record stream is at end-of-file (end-of-file indicator set), rnbgetl returns zero (0L). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rnbgetl returns zero (0L). 1.3.19 The rnbgetui Function Synopsis #include <recio.h> unsigned int rnbgetui(REC *rp, unsigned int num, int base); Description The rnbgetui function reads a field consisting of one non-negative integral number represented by the radix determined by the value of base from the field number num for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. The first field in a record is field number 1, the second field is field number 2, etc. Base may be zero or in the range of 2 to 36 inclusive. If the value of base is zero, the expected form of the integral number is described by section 3.1.3.2 of ANSI X3.159-1989. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero. Returns The rnbgetui function returns an unsigned integer from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rnbgetui returns zero. If the record stream is at end-of-file (end-of-file indicator set), rnbgetui returns zero. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rnbgetui returns zero. 1.3.20 The rnbgetul Function Synopsis #include <recio.h> unsigned long rnbgetul(REC *rp, unsigned int num, int base); Description The rnbgetul function reads a field consisting of one non-negative integral number represented by the radix determined by the value of base from the field number num for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. The first field in a record is field number 1, the second field is field number 2, etc. Base may be zero or in the range of 2 to 36 inclusive. If the value of base is zero, the expected form of the integral number is described by section 3.1.3.2 of ANSI X3.159-1989. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero (0L). Returns The rnbgetul function returns an unsigned long from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rnbgetul returns zero (0L). If the record stream is at end-of-file (end-of-file indicator set), rnbgetul returns zero (0L). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rnbgetul returns zero (0L). 1.3.21 The rngetc Function Synopsis #include <recio.h> int rngetc(REC *rp, unsigned int num); Description The rngetc function reads a field consisting of one non-white space character from the field number num for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. The first field in a record is field number 1, the second field is field number 2, etc. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns EOF. Returns The rngetc function returns a character from a single non-white space character field in the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, or if there is more than or less than one non-white character in the field, the error indicator for the record stream is set, and rngetc returns EOF. If the record stream is at end-of-file (end-of-file indicator set), rngetc returns EOF. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rngetc returns EOF. 1.3.22 The rngetd Function Synopsis #include <recio.h> double rngetd(REC *rp, unsigned int num); Description The rngetd function reads a field consisting of one floating point number from the field number num for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. The first field in a record is field number 1, the second field is field number 2, etc. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero. Returns The rngetd function returns a double precision floating point number from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rngetd returns zero (0.0). If the record stream is at end-of-file (end-of-file indicator set), rngetd returns zero (0.0). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rngetd returns zero (0.0). 1.3.23 The rngetf Function Synopsis #include <recio.h> float rngetf(REC *rp, unsigned int num); Description The rngetf function reads a field consisting of one floating point number from the field number num for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. The first field in a record is field number 1, the second field is field number 2, etc. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero. Returns The rngetf function returns a single precision floating point number from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rngetf returns zero (0.0). If the record stream is at end-of-file (end-of-file indicator set), rngetf returns zero (0.0). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rngetf returns zero (0.0). 1.3.24 The rngeti Function Synopsis #include <recio.h> int rngeti(REC *rp, unsigned int num); Description The rngeti function reads a field consisting of one integral number from the field number num for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. The first field in a record is field number 1, the second field is field number 2, etc. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero. Returns The rngeti function returns a signed integer from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rngeti returns zero. If the record stream is at end-of-file (end-of-file indicator set), rngeti returns zero. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rngeti returns zero. 1.3.25 The rngetl Function Synopsis #include <recio.h> long rngetl(REC *rp, unsigned int num); Description The rngetl function reads a field consisting of one integral number from the field number num for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. The first field in a record is field number 1, the second field is field number 2, etc. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero (0L). Returns The rngetl function returns a signed long from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rngetl returns zero (0L). If the record stream is at end-of-file (end-of-file indicator set), rngetl returns zero (0L). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rngetl returns zero (0L). 1.3.26 The rngets Function Synopsis #include <recio.h> char *rngets(REC *rp, unsigned int num); Description The rngets function reads a field consisting of one text string from the field number num for the input record stream pointed to by rp. Any leading white space before the text delimiter and any trailing white space after the text delimiter in the field is ignored. The text delimiters are not returned as part of the string. The first field in a record is field number 1, the second field is field number 2, etc. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns a pointer to an empty string. Returns The rngets function returns a pointer to a character array from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, the error indicator for the record stream is set, and rngets returns a pointer to an empty string. If the record stream is at end-of-file (end-of-file indicator set), rngets returns a pointer to an empty string. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rngets returns a pointer to an empty string. 1.3.27 The rngett Function Synopsis #include <recio.h> time_t rngett(REC *rp, unsigned int num); Description The rngett function reads a field consisting of one time of type time_t from the field number num for input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. The first field in a record is field number 1, the second field is field number 2, etc. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns (time_t)-1. Returns The rngett function returns a time of type time_t. If an attempt is made to read beyond the end-of-record, the error indicator for the record stream is set, and rngett returns (time_t)-1. If the record stream is at end-of-file (end-of-file indicator set), rngett returns (time_t)-1. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rngett returns (time_t)-1. 1.3.28 The rngettm Function Synopsis #include <recio.h> struct tm rngettm(REC *rp, unsigned int num); Description The rngettm function reads a field consisting of one time of type struct tm from the field number num for input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. The first field in a record is field number 1, the second field is field number 2, etc. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns an implementation defined value. Returns The rngettm function returns a time of type struct tm. If an attempt is made to read beyond the end-of-record, the error indicator for the record stream is set, and rngettm returns an implementation defined value. If the record stream is at end-of-file (end-of-file indicator set), rngettm returns an implementation defined value. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rngettm returns an implementation defined value. 1.3.29 The rngetui Function Synopsis #include <recio.h> unsigned int rngetui(REC *rp, unsigned int num); Description The rngetui function reads a field consisting of one non-negative integral number from the field number num for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. The first field in a record is field number 1, the second field is field number 2, etc. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero. Returns The rngetui function returns an unsigned integer from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rngetui returns zero. If the record stream is at end-of-file (end-of-file indicator set), rngetui returns zero. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rngetui returns zero. 1.3.30 The rngetul Function Synopsis #include <recio.h> unsigned long rngetul(REC *rp, unsigned int num); Description The rngetul function reads a field consisting of one non-negative integral number from the field number num for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. The first field in a record is field number 1, the second field is field number 2, etc. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero (0L). Returns The rngetul function returns an unsigned long from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rngetul returns zero (0L). If the record stream is at end-of-file (end-of-file indicator set), rngetul returns zero (0L). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rngetul returns zero (0L). 1.3.31 The rsetfldch Function Synopsis #include <recio.h> void rsetfldch(REC *rp, int ch); Description The rsetfldch function sets the field delimiter to the character ch for the record stream pointed to by rp. If the character ch is the space character ' ', then the field is delimited by any white-space, and multiple contiguous white space characters are treated as a single delimiter. If the character ch is other than the space character, then multiple contiguous field delimiters are treated as a series of empty fields. If rsetfldch is not called, the field delimiter is set by the value of the macro RECFLDCH. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rsetfldch function returns no value. 1.3.32 The rsettmfmt Function Synopsis #include <recio.h> void rsettmfmt(REC *rp, char *fmt); Description The rsettmfmt function sets the time format according to the string fmt for the record stream pointed to by rp. Time formats are specified using a subset of the specifiers from the ANSI-C strftime function. Supported specifiers are: %d - day of month (1-31) %H - hour from 24-hour clock (0-23) %m - month (1-12) %M - minute (0-59) %s - second (0-61) %y - year without century (00-99) %Y - year with century (e.g. 1994) If the rsettmfmt function is not called, the time format is set to "%m/%d/%y". If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rsettmfmt function returns no value. 1.3.33 The rsettxtch Function Synopsis #include <recio.h> void rsettxtch(REC *rp, int ch); Description The rsettxtch function sets the text delimiter to the character ch for the record stream pointed to by rp. If rsettxtch is not called, the text delimiter is set by the value of the macro RECTXTCH. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rsettxtch function returns no value. 1.3.34 The rskipfld Function Synopsis #include <recio.h> void rskipfld(REC *rp); Description The rskipfld function skips to the next field for the record stream pointed to by rp. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rskipfld function returns no value. 1.3.35 The rskipnfld Function Synopsis #include <recio.h> void rskipnfld(REC *rp, unsigned int num); Description The rskipnfld function skips over num number of fields for the record stream pointed to by rp. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rskipnfld function returns no value. 1.4 Character Delimited Field Output Functions The character delimited field output functions automatically place the field delimiter character between fields in the output. 1.4.1 The rbputi Function Synopsis #include <recio.h> void rbputi(REC *rp, int base, int number); Description The rbputi function writes an integral number in the radix base to the output record stream pointed to by rp. Base may be between 2 to 36. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rbputi function returns no value. 1.4.2 The rbputl Function Synopsis #include <recio.h> void rbputl(REC *rp, int base, long number); Description The rbputl function writes an integral number in the radix base to the output record stream pointed to by rp. Base may be between 2 to 36. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rbputl function returns no value. 1.4.3 The rbputui Function Synopsis #include <recio.h> void rbputui(REC *rp, int base, unsigned int number); Description The rbputui function writes an unsigned integral number in the radix base to the output record stream pointed to by rp. Base may be between 2 to 36. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rbputui function returns no value. 1.4.4 The rbputul Function Synopsis #include <recio.h> void rbputul(REC *rp, int base, unsigned long number); Description The rbputul function writes an unsigned integral number in the radix base to the output record stream pointed to by rp. Base may be between 2 to 36. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rbputul function returns no value. 1.4.5 The rputc Function Synopsis #include <recio.h> void rputc(REC *rp, int ch); Description The rputc function writes a character ch to the output record stream pointed to by rp. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rputc function returns no value. 1.4.6 The rputd Function Synopsis #include <recio.h> void rputd(REC *rp, double number); Description The rputd function writes a floating point number to the output record stream pointed to by rp. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rputd function returns no value. 1.4.7 The rputf Function Synopsis #include <recio.h> void rputf(REC *rp, float number); Description The rputf function writes a floating point number to the output record stream pointed to by rp. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rputf function returns no value. 1.4.8 The rputi Function Synopsis #include <recio.h> void rputi(REC *rp, int number); Description The rputi function writes an integral number to the output record stream pointed to by rp. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rputi function returns no value. 1.4.9 The rputl Function Synopsis #include <recio.h> void rputl(REC *rp, long number); Description The rputl function writes an integral number to the output record stream pointed to by rp. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rputl function returns no value. 1.4.10 The rputs Function Synopsis #include <recio.h> void rputs(REC *rp, char *string); Description The rputs function writes a string of characters to the output record stream pointed to by rp. If the text delimiter character is not the space character, text delimiters are placed around the text. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rputs function returns no value. 1.4.11 The rputt Function Synopsis #include <recio.h> void rputt(REC *rp, time_t time); Description The rputt function writes the time to the output record stream pointed to by rp. The format of the time is determined by the time format for the record stream. See section 1.3.16 on how to set the time format. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rputt function returns no value. 1.4.12 The rputtm Function Synopsis #include <recio.h> void rputtm(REC *rp, struct tm t); Description The rputtm function writes out the time as specified by the contents of struct tm t to the output record stream pointed to by rp. The format of the time is determined by the time format for the record stream. See section 1.3.16 on how to set the time format. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rputtm function returns no value. 1.4.13 The rputui Function Synopsis #include <recio.h> void rputui(REC *rp, unsigned int number); Description The rputui function writes an unsigned integral number to the output record stream pointed to by rp. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rputui function returns no value. 1.4.14 The rputul Function Synopsis #include <recio.h> void rputul(REC *rp, unsigned long number); Description The rputul function writes an unsigned integral number to the output record stream pointed to by rp. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rputul function returns no value. 1.5 Column Delimited Field Input Functions The column delimited field input functions use column positions to determine the start and end of each field. 1.5.1 The rcbgeti Function Synopsis #include <recio.h> int rcbgeti(REC *rp, size_t begcol, size_t endcol, int base); Description The rcbgeti function gets one integral number represented by the radix determined by the value of base and contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. Base may be zero or in the range of 2 to 36 inclusive. If the value of base is zero, the expected form of the integral number is described by section 3.1.3.2 of ANSI X3.159-1989. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero. Returns The rcbgeti function returns a signed integer from the input record stream pointed to by rp. If begcol is beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rcbgeti returns zero. If the record stream is at end-of-file (end-of-file indicator set), rcbgeti returns zero. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcbgeti returns zero. 1.5.2 The rcbgetl Function Synopsis #include <recio.h> long rcbgetl(REC *rp, size_t begcol, size_t endcol, int base); Description The rcbgetl function gets one integral number represented by the radix determined by the value of base and contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. Base may be zero or in the range of 2 to 36 inclusive. If the value of base is zero, the expected form of the integral number is described by section 3.1.3.2 of ANSI X3.159-1989. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero (0L). Returns The rcbgetl function returns a signed long from the input record stream pointed to by rp. If begcol is beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rcbgetl returns zero (0L). If the record stream is at end-of-file (end-of-file indicator set), rcbgetl returns zero (0L). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcbgetl returns zero (0L). 1.5.3 The rcbgetui Function Synopsis #include <recio.h> unsigned int rcbgetui(REC *rp, size_t begcol, size_t endcol, int base); Description The rcbgetui function gets one non-negative integral number represented by the radix determined by the value of base and contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. Base may be zero or in the range of 2 to 36 inclusive. If the value of base is zero, the expected form of the integral number is described by section 3.1.3.2 of ANSI X3.159-1989. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero. Returns The rcbgetui function returns an unsigned integer from the input record stream pointed to by rp. If begcol is beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rcbgetui returns zero. If the record stream is at end-of-file (end-of-file indicator set), rcbgetui returns zero. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcbgetui returns zero. 1.5.4 The rcbgetul Function Synopsis #include <recio.h> unsigned long rcbgetul(REC *rp, size_t begcol, size_t endcol, int base); Description The rcbgetul function gets one non-negative integral number represented by the radix determined by the value of base and contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. Base may be zero or in the range of 2 to 36 inclusive. If the value of base is zero, the expected form of the integral number is described by section 3.1.3.2 of ANSI X3.159-1989. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero (0L). Returns The rcbgetul function returns an unsigned long from the input record stream pointed to by rp. If begcol is beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rcbgetul returns zero (0L). If the record stream is at end-of-file (end-of-file indicator set), rcbgetul returns zero (0L). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcbgetul returns zero (0L). 1.5.5 The rcgetc Function Synopsis #include <recio.h> int rcgetc(REC *rp, size_t col); Description The rcgetc function obtains from column position col the unsigned char converted to an int from the input record stream pointed to by rp. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns EOF. Returns The rcgetc function returns a character from column position col from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, the error indicator for the record stream is set, and rcgetc returns EOF. If the record stream is at end-of-file (end-of-file indicator set), rcgetc returns EOF. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcgetc returns EOF. 1.5.6 The rcgetd Function Synopsis #include <recio.h> double rcgetd(REC *rp, size_t begcol, size_t endcol); Description The rcgetd function gets one floating point number contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero. Returns The rcgetd function returns a double precision floating point number from the input record stream pointed to by rp. If begcol is beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rcgetd returns zero (0.0). If the record stream is at end-of-file (end-of-file indicator set), rcgetd returns zero (0.0). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcgetd returns zero (0.0). 1.5.7 The rcgetf Function Synopsis #include <recio.h> float rcgetf(REC *rp, size_t begcol, size_t endcol); Description The rcgetf function gets one floating point number contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero. Returns The rcgetf function returns a single precision floating point number from the input record stream pointed to by rp. If begcol is beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rcgetf returns zero (0.0). If the record stream is at end-of-file (end-of-file indicator set), rcgetf returns zero (0.0). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcgetf returns zero (0.0). 1.5.8 The rcgeti Function Synopsis #include <recio.h> int rcgeti(REC *rp, size_t begcol, size_t endcol); Description The rcgeti function gets one integral number contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero. Returns The rcgeti function returns a signed integer from the input record stream pointed to by rp. If begcol is beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rcgeti returns zero. If the record stream is at end-of-file (end-of-file indicator set), rcgeti returns zero. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcgeti returns zero. 1.5.9 The rcgetl Function Synopsis #include <recio.h> long rcgetl(REC *rp, size_t begcol, size_t endcol); Description The rcgetl function gets one integral number contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero (0L). Returns The rcgetl function returns a signed long from the input record stream pointed to by rp. If begcol is beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rcgetl returns zero (0L). If the record stream is at end-of-file (end-of-file indicator set), rcgetl returns zero (0L). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcgetl returns zero (0L). 1.5.10 The rcgets Function Synopsis #include <recio.h> char *rcgets(REC *rp, size_t begcol, size_t endcol); Description The rcgets function gets a string contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. The rcgets function does not remove any leading or trailing white space, nor does it remove any text delimiter characters. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns a pointer to an empty string. Returns The rcgets function returns a pointer to a character array from the input record stream pointed to by rp. If begcol is beyond the end-of-record, the error indicator for the record stream is set, and rcgets returns a pointer to an empty string. If the record stream is at end-of-file (eof indicator set), rcgets returns a pointer to an empty string. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcgets returns a pointer to an empty string. 1.5.11 The rcgett Function Synopsis #include <recio.h> time_t rcgett(REC *rp, size_t begcol, size_t endcol); Description The rcgett function reads a field consisting of one time of type time_t contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns (time_t)-1. Returns The rcgett function returns a time of type time_t. If an attempt is made to read beyond the end-of-record, the error indicator for the record stream is set, and rcgett returns (time_t)-1. If the record stream is at end-of-file (end-of-file indicator set), rcgett returns (time_t)-1. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcgett returns (time_t)-1. 1.5.12 The rcgettm Function Synopsis #include <recio.h> struct tm rcgettm(REC *rp, size_t begcol, size_t endcol); Description The rcgettm function reads a field consisting of one time of type struct tm contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and an implementation defined value is returned. Returns The rcgettm function returns a time of type struct tm. If an attempt is made to read beyond the end-of-record, the error indicator for the record stream is set, and rcgettm returns an implementation defined value. If the record stream is at end-of-file (end-of-file indicator set), rcgettm returns an implementation defined value. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcgettm returns an implementation defined value. 1.5.13 The rcgetui Function Synopsis #include <recio.h> unsigned int rcgetui(REC *rp, size_t begcol, size_t endcol); Description The rcgetui function gets one non-negative integral number contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero. Returns The rcgetui function returns an unsigned integer from the input record stream pointed to by rp. If begcol is beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rcgetui returns zero. If the record stream is at end-of-file (end-of-file indicator set), rcgetui returns zero. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcgetui returns zero. 1.5.14 The rcgetul Function Synopsis #include <recio.h> unsigned long rcgetul(REC *rp, size_t begcol, size_t endcol); Description The rcgetul function gets one non-negative integral number contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the function returns zero (0L). Returns The rcgetul function returns an unsigned long from the input record stream pointed to by rp. If begcol is beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rcgetul returns zero (0L). If the record stream is at end-of-file (end-of-file indicator set), rcgetul returns zero (0L). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcgetul returns zero (0L). 1.6 Column Delimited Field Output Functions The column delimited field output functions automatically place the number, string or character between the specified columns in the output. 1.6.1 The rcbputi Function Synopsis #include <recio.h> void rcbputi(REC *rp, size_t begcol, size_t endcol, int base, int number); Description The rcbputi function writes an integral number in the radix base from column begcol to column endcol of the output record stream pointed to by rp. Base may be between 2 to 36. If the number is too large to fit between the columns, asterisks are printed between the columns and the callback warning function is called. The warning indicator for the record stream is set. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rcbputi function returns no value. 1.6.2 The rcbputl Function Synopsis #include <recio.h> void rcbputl(REC *rp, size_t begcol, size_t endcol, int base, long number); Description The rcbputl function writes an integral number in the radix base from column begcol to column endcol of the output record stream pointed to by rp. Base may be between 2 to 36. If the number is too large to fit between the columns, asterisks are printed between the columns and the callback warning function is called. The warning indicator for the record stream is set. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rcbputl function returns no value. 1.6.3 The rcbputui Function Synopsis #include <recio.h> void rcbputui(REC *rp, size_t begcol, size_t endcol, int base, unsigned int number); Description The rcbputui function writes an unsigned integral number in the radix base from column begcol to column endcol of the output record stream pointed to by rp. Base may be between 2 to 36. If the number is too large to fit between the columns, asterisks are printed between the columns and the callback warning function is called. The warning indicator for the record stream is set. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rcbputui function returns no value. 1.6.4 The rcbputul Function Synopsis #include <recio.h> void rcbputul(REC *rp, size_t begcol, size_t endcol, int base, unsigned long number); Description The rcbputul function writes an unsigned integral number in the radix base from column begcol to column endcol of the output record stream pointed to by rp. Base may be between 2 to 36. If the number is too large to fit between the columns, asterisks are printed between the columns and the callback warning function is called. The warning indicator for the record stream is set. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rcbputul function returns no value. 1.6.5 The rcputc Function Synopsis #include <recio.h> void rcputc(REC *rp, size_t col, int ch); Description The rcputc function writes a character ch at column col of the output record stream pointed to by rp. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rcputc function returns no value. 1.6.6 The rcputd Function Synopsis #include <recio.h> void rcputd(REC *rp, size_t begcol, size_t endcol, double number); Description The rcputd function writes a floating point number from column begcol to column endcol of the output record stream pointed to by rp. If the number is too large to fit between the columns, asterisks are printed between the columns and the callback warning function is called. The warning indicator for the record stream is set. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rcputd function returns no value. 1.6.7 The rcputf Function Synopsis #include <recio.h> void rcputf(REC *rp, size_t begcol, size_t endcol, float number); Description The rcputf function writes a floating point number from column begcol to column endcol of the output record stream pointed to by rp. If the number is too large to fit between the columns, asterisks are printed between the columns and the callback warning function is called. The warning indicator for the record stream is set. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rcputf function returns no value. 1.6.8 The rcputi Function Synopsis #include <recio.h> void rcputi(REC *rp, size_t begcol, size_t endcol, int number); Description The rcputi function writes an integral number from column begcol to column endcol of the output record stream pointed to by rp. If the number is too large to fit between the columns, asterisks are printed between the columns and the callback warning function is called. The warning indicator for the record stream is set. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rcputi function returns no value. 1.6.9 The rcputl Function Synopsis #include <recio.h> void rcputl(REC *rp, size_t begcol, size_t endcol, long number); Description The rcputl function writes an integral number from column begcol to column endcol of the output record stream pointed to by rp. If the number is too large to fit between the columns, asterisks are printed between the columns and the callback warning function is called. The warning indicator for the record stream is set. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rcputl function returns no value. 1.6.10 The rcputs Function Synopsis #include <recio.h> void rcputs(REC *rp, size_t begcol, size_t endcol, char *string); Description The rcputs function writes a string of characters from column begcol to column endcol of the output record stream pointed to by rp. If the string is too large to fit between the columns, a truncated string is output and the callback warning function is called. The warning indicator for the record stream is set. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rcputs function returns no value. 1.6.11 The rcputt Function Synopsis #include <recio.h> void rcputt(REC *rp, size_t begcol, size_t endcol, time_t time); Description The rcputt function writes the time from column begcol to column endcol of the output record stream pointed to by rp. The format of the time is determined by the time format for the record stream. See section 1.3.16 on how to set the time format. If the time is too large to fit between the columns, asterisks are printed between the columns and the callback warning function is called. The warning indicator for the record stream is set. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rcputt function returns no value. 1.6.12 The rcputtm Function Synopsis #include <recio.h> void rcputtm(REC *rp, size_t begcol, size_t endcol, struct tm t); Description The rcputtm function writes out the time as specified by the contents of struct tm t from column begcol to column endcol of the output record stream pointed to by rp. The format of the time is determined by the time format for the record stream. See section 1.3.16 on how to set the time format. If the time is too large to fit between the columns, asterisks are printed between the columns and the callback warning function is called. The warning indicator for the record stream is set. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rcputtm function returns no value. 1.6.13 The rcputui Function Synopsis #include <recio.h> void rcputui(REC *rp, size_t begcol, size_t endcol, unsigned int number); Description The rcputui function writes an unsigned integral number from column begcol to column endcol of the output record stream pointed to by rp. If the number is too large to fit between the columns, asterisks are printed between the columns and the callback warning function is called. The warning indicator for the record stream is set. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rcputui function returns no value. 1.6.14 The rcputul Function Synopsis #include <recio.h> void rcputul(REC *rp, size_t begcol, size_t endcol, unsigned long number); Description The rcputul function writes an unsigned integral number from column begcol to column endcol of the output record stream pointed to by rp. If the number is too large to fit between the columns, asterisks are printed between the columns and the callback warning function is called. The warning indicator for the record stream is set. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rcputul function returns no value. 1.7 Current Position Functions 1.7.1 The rbegcolno Function Synopsis #include <recio.h> int rbegcolno(REC *rp); Description The rbegcolno function gets the current setting of the first column number in the record for the record stream pointed to by rp. Returns The rbegcolno function returns 0 if column numbering starts with zero or 1 if column numbering starts with one. 1.7.2 The rcolno Function Synopsis #include <recio.h> size_t rcolno(REC *rp); Description The rcolno function gets the current column number of the current record for the record stream pointed to by rp. Returns The rcolno function returns the current column number of the current record for the record stream pointed to by rp. The rcolno function returns zero prior to the reading of the first record. 1.7.3 The rflds Function Synopsis #include <recio.h> char *rflds(REC *rp); Description The rflds function gets a pointer to the field buffer associated with the record stream pointed to by rp. The last field read from the current record is stored in the field buffer. The field is terminated by a null character. Returns The rflds function returns a pointer to the field buffer associated with the record stream pointed to by rp. 1.7.4 The rfldno Function Synopsis #include <recio.h> size_t rfldno(REC *rp); Description The rfldno function gets the number of fields that have been read from the current record for the record stream pointed to by rp. Returns The rfldno function returns the number of fields that have been read from the current record for the record stream pointed to by rp. 1.7.5 The rgetfldpos Function Synopsis #include <recio.h> void rgetfldpos(REC *rp, rpos_t &pos) Description The rgetfldpos function stores the current value of the field position indicator of the current record for the input stream pointed to by rp into the object pointed to by pos. The value stored contains unspecified information usable by the rsetfldpos function to set the field position of the current record to the same position as when the rgetfldpos function was called. If an error occurs, the error indicator for the record stream is set, and the callback error function is called. Returns The rgetfldpos function returns no value. 1.7.6 The rnames Function Synopsis #include <recio.h> char *rnames(REC *rp); Description The rnames function gets a pointer to the name of the file associated with the record stream pointed to by rp. Returns The rnames function returns a pointer to the name of the file associated with the record stream pointed to by rp. 1.7.7 The rgetrec Function Synopsis #include <recio.h> char *rgetrec(REC *rp); Description The rgetrec function gets the next record from the record stream pointed to by rp. The rgetrec function increments the record number, clears the field number to zero, resets the column number to rbegcolno(), and returns a pointer to the record buffer. Record numbering starts at one (1L). Before the first record in a record stream is read into the record buffer, the record number is zero. Field numbering starts at one (1). Before the first field in a record is read into the field buffer, the field number is zero. Column numbering starts at either zero or one, depending on the setting of the rsetbegcolno function. Column numbering defaults to zero. If an error occurs, the error indicator for the record stream is set, the callback error function is called, and the rgetrec function returns a null pointer. If the end-of-file is reached, the end-of-file indicator for the record stream is set and the rgetrec function returns a null pointer. Returns The rgetrec function returns a pointer to the record buffer if the next record was successfully read. A null pointer is returned on either error or end-of-file. 1.7.8 The rnumfld Function Synopsis #include <recio.h> unsigned int rnumfld(REC *rp); Description The rnumfld function gets the number of fields in the current record for the input record stream pointed to by rp. If an error occurs, the error indicator for the record stream is set, and the callback error function is called. Returns The rnumfld function returns the number of fields in the current record. 1.7.9 The rputrec Function Synopsis #include <recio.h> void rputrec(REC *rp); Description The rputrec function writes the end-of-record newline character to the output record stream pointed to by rp. The rputrec function increments the record number, clears the field number to zero, resets the column number to either zero or one, depending on the setting of the rsetbegcolno function. Record numbering starts at one (1L). Before the first record in a record stream is written, the record number is zero. Field numbering starts at one (1). Before the first field in a record is written, the field number is zero. Column numbering starts at either zero or one, depending on the setting of the rsetbegcolno function. Column numbering defaults to zero. If an error occurs, the error indicator for the record stream is set, and the callback error function is called. Returns The rputrec function returns no value. 1.7.10 The rrecs Function Synopsis #include <recio.h> char *rrecs(REC *rp); Description The rrecs function gets a pointer to the record buffer associated with the record stream pointed to by rp. The current record is stored in the record buffer. The record is terminated by a null character. Returns The rrecs function returns a pointer to the record buffer associated with the record stream pointed to by rp. 1.7.11 The rrecno Function Synopsis #include <recio.h> long rrecno(REC *rp); Description The rrecno function gets the number of records that have been read from the record stream pointed to by rp. Returns The rrecno function returns the number of records that have been read from the record stream pointed to by rp. 1.7.12 The rresetrec Function Synopsis #include <recio.h> void rresetrec(REC *rp); Description The rresetrec function resets the internals of the input stream pointed to by rp such that the next use of a rget field function reads from the beginning of the record buffer. It has no effect on an output stream. Returns The rresetrec function returns no value. 1.7.13 The rsetbegcolno Function Synopsis #include <recio.h> void rsetbegcolno(REC *rp, int colno); Description The rsetbegcolno function sets the first column number colno for the record stream pointed to by rp. Column numbering can start at either 0 or 1. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rsetbegcolno function returns no value. 1.7.14 The rsetbegyr Function Synopsis #include <recio.h> void rsetbegyr(int year) Description The rsetbegyr function sets the beginning 4-digit year of the range of the 2-digit time format %y (see section 1.3.16). If not this function is not used, the beginning year is controlled by the value of the constant macro RECBEGYR. Returns The rsetbegyr function returns no value. 1.7.15 The rsetfldpos Function Synopsis #include <recio.h> void rsetfldpos(REC *rp, rpos_t &pos); Description The rsetfldpos function sets the field position indicator of the current record of the input stream pointed to by rp according to the value of the object pointed to by pos, which is a value obtained from an earlier call to the rgetfldpos function on the same stream. If the record has changed since the earlier call to the rgetfldpos function, the behavior of this function is implementation dependent. If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rsetfldpos function returns no value. 1.7.16 The rsetfldstr Function Synopsis #include <recio.h> void rsetfldstr(REC *rp, char *s); Description The rsetfldstr function copies the string s into the field buffer of the record stream pointed to by rp. Any existing string in the field buffer is overwritten. The field buffer size is increased, if necessary, to accommodate the string. A side effect of using the rsetfldstr function is that the error and end-of-file indicators for the record stream are cleared (provided rsetfldstr does not create an error). If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rsetfldstr function returns no value. 1.7.17 The rsetrecstr Function Synopsis #include <recio.h> void rsetrecstr(REC *rp, char *s); Description The rsetrecstr function copies the string s into the record buffer of the input record stream pointed to by rp. Any existing string in the record buffer is overwritten. The record buffer size is increased, if necessary, to accommodate the string. It has no effect on an output stream. A side effect of using the rsetrecstr function is that the error and end-of-file indicators for the record stream are cleared (provided rsetrecstr does not create an error). If an error occurs, the error indicator for the record stream is set and the callback error function is called. Returns The rsetrecstr function returns no value. 1.8 Error Functions 1.8.1 The errno Macro Synopsis #include <errno.h> Description The errno macro "expands to a modifiable lvalue that has type int, the value of which is set to a positive error number by several library functions." -Section 4.1.3 of ANSI X3.159-1989. 1.8.2 The rclearerr Function Synopsis #include <recio.h> void rclearerr(REC *rp); Description The rclearerr function clears the end-of-file and error indicators for the record stream pointed to by rp. Returns The rclearerr function returns no value. 1.8.3 The rcxtno Function Synopsis #include <recio.h> int rcxtno(REC *rp); Description The rcxtno function gets the context number from the record stream pointed to by rp. Context numbers can be assigned to a record stream using the rsetcxtno function. A zero context number indicates that the context number has not been assigned. The recin, recout, recerr, and recprn streams return the macro values of RECIN, RECOUT, RECERR, and RECPRN respectively. Returns The rcxtno function returns the context number from the record stream pointed to by rp. 1.8.4 The reof Function Synopsis #include <recio.h> int reof(REC *rp); Description The reof function tests the end-of-file indicator for the record stream pointed to by rp. Returns The reof function returns nonzero if and only if the end-of-file indicator is set for the record stream pointed to by rp. 1.8.5 The rerror Function Synopsis #include <recio.h> int rerror(REC *rp); Description The rerror function tests the error indicator for the record stream pointed to by rp. Returns The rerror function returns nonzero if and only if the error indicator is set for the record stream pointed to by rp. 1.8.6 The rerrstr Function Synopsis #include <recio.h> char *rerrstr(REC *rp); Description The rerrstr function gets the error message for the record stream pointed to by rp. The text of the error message is implementation dependent. Returns The rerrstr function returns a pointer to a string containing an error message. 1.8.7 The risvalid Function Synopsis #include <recio.h> int risvalid(REC *rp); Description The risvalid function tests if rp is a valid pointer to a record stream. Returns The risvalid function returns a nonzero value if and only if rp is a valid pointer to an open record stream. 1.8.8 The rsetcxtno Function Synopsis #include <recio.h> void rsetcxtno(REC *rp, int cxtno); Description The rsetcxtno function sets the context number cxtno on the record stream pointed to by rp. Assigning a context number allows a file format to be more easily identified in the callback error function. Negative context numbers are reserved; a zero context number indicates an that the context has not been assigned. A macro values RECIN, RECOUT, RECERR, and RECPRN are preassigned to the recin, recout, recerr, and recprn streams respectively. Returns The rsetcxtno returns no value. 1.8.9 The rseterr Function Synopsis #include <recio.h> int rseterr(REC *rp, int errnum); Description The rseterr function sets the global error number errno to the value of errnum if the record stream pointed to by rp is null. If rp points to a valid record stream, the rseterr function sets the error indicator on the record stream. The callback error function is called. If the record stream error indicator is already set on entry to the rseterr function, the rseterr function does nothing. Returns The rseterr function returns the error number. If the callback error function corrects the error and clears the error number, the function returns zero. 1.8.10 The rseterrfn Function Synopsis #include <recio.h> void rseterrfn(void(*rerrfn)(REC *rp)); Description The rseterrfn function registers the callback error function rerrfn for the record stream pointed to by rp. Returns The rseterrfn function returns no value. The callback error function rerrfn returns no value. 1.8.11 The rstrerror Function Synopsis #include <recio.h> char *rstrerror(int errnum); Description The rstrerror function maps the error number in errnum to an error message string. The error number and the text of the error message are implementation dependent. (To map errno to an error string, use the strerror function.) Returns The rstrerror function returns a pointer to a string containing an error message. 1.9 Warning Functions 1.9.1 The rclearwarn Function Synopsis #include <recio.h> void rclearwarn(REC *rp); Description The rclearwarn function clears the warning indicator for the record stream pointed to by rp. Returns The rclearwarn function returns no value. 1.9.2 The rsetwarn Function Synopsis #include <recio.h> int rsetwarn(REC *rp, int warnum); Description The rsetwarn function sets the warning indicator on the record stream pointed to by rp. The callback warning function is called (if registered). Returns The rsetwarn function returns the warning number. If the callback warning function modifies the warning number, the function returns the modified warning number. 1.9.3 The rsetwarnfn Function Synopsis #include <recio.h> void rsetwarnfn(void(*rwarnfn)(REC *rp)); Description The rsetwarnfn function registers the callback warning function rwarnfn for the record stream pointed to by rp. Returns The rsetwarnfn function returns no value. The callback warning function rwarnfn returns no value. 1.9.4 The rstrwarning Function Synopsis #include <recio.h> char *rstrwarning(int warnum); Description The rstrwarning function maps the warning number warnum to an warning message string. The warning number and the text of the warning message are implementation dependent. Returns The rstrwarning function returns a pointer to a string containing an warning message. 1.9.5 The rwarning Function Synopsis #include <recio.h> int rwarning(REC *rp); Description The rwarning function tests the warning indicator for the record stream pointed to by rp. Returns The rwarning function returns nonzero if and only if the warning indicator is set for the record stream pointed to by rp. 1.9.6 The rwarnstr Function Synopsis #include <recio.h> char *rwarnstr(REC *rp); Description The rwarnstr function gets the warning message for the record stream pointed to by rp. The text of the warning message is implementation dependent. Returns The rwarnstr function returns a pointer to a string containing an warning message. 2.0 PORTABILITY ISSUES The first six characters of many recio functions are common to other recio functions. Ref 3.1.2 of ANSI X3.159-1989. References are not implemented in ANSI X3.159-1989, but are part of C++. They can be reasonably simulated in C (for functions that don't have a variable number of arguments) by use of a macro that inserts the & into the call. (1.7.5, 1.7.15) 3.0 REFERENCES 1. ANSI X3.159-1989. American National Standard for Information Systems - Programming Language - C. American National Standards Institute, 11 West 42nd Street, New York, NY 10036, 1990. 4.0 INDEX errno macro ............ 1.8.1 FLDBUFSIZ macro ........ 1.1.3, 1.2.4 rbegcolno function ..... 1.7.1, 1.7.7 rbgeti function ........ 1.3.1 rbgetl function ........ 1.3.2 rbgetui function ....... 1.3.3 rbgetul function ....... 1.3.4 rbputi function ........ 1.4.1 rbputl function ........ 1.4.2 rbputui function ....... 1.4.3 rbputul function ....... 1.4.4 rcbgeti function ....... 1.5.1 rcbgetl function ....... 1.5.2 rcbgetui function ...... 1.5.3 rcbgetul function ...... 1.5.4 rcbputi function ....... 1.6.1 rcbputl function ....... 1.6.2 rcbputui function ...... 1.6.3 rcbputul function ...... 1.6.4 rcgetc function ........ 1.5.5 rcgetd function ........ 1.5.6 rcgetf function ........ 1.5.7 rcgeti function ........ 1.5.8 rcgetl function ........ 1.5.9 rcgets function ........ 1.5.10 rcgett function ........ 1.5.11 rcgettm function ....... 1.5.12 rcgetui function ....... 1.5.13 rcgetul function ....... 1.5.14 rclearerr function ..... 1.8.2 rclearwarn function .... 1.9.1 rclose function ........ 1.2.1 rcloseall function ..... 1.2.2 rcolno function ........ 1.7.2 rcputc function ........ 1.6.5 rcputd function ........ 1.6.6 rcputf function ........ 1.6.7 rcputi function ........ 1.6.8 rcputl function ........ 1.6.9 rcputs function ........ 1.6.10 rcputt function ........ 1.6.11 rcputtm function ....... 1.6.12 rcputui function ....... 1.6.13 rcputul function ....... 1.6.14 rcxtno function ........ 1.8.3 REC object ............. 1.1.2 recin expression ....... 1.1.4 RECBUFSIZ macro ........ 1.1.3, 1.2.5 RECFLDCH macro ......... 1.1.3, 1.3.15 RECTXTCH macro ......... 1.1.3, 1.3.17 reof function .......... 1.8.4 rerror function ........ 1.8.5 rerrstr function ....... 1.8.6 rflds function ......... 1.7.3 rfldno function ........ 1.7.4 rgetc function ......... 1.3.5 rgetd function ......... 1.3.6 rgetf function ......... 1.3.7 rgetfldpos function .... 1.7.5 rgeti function ......... 1.3.8 rgetl function ......... 1.3.9 rgetrec function ....... 1.7.7 rgets function ......... 1.3.10 rgett function ......... 1.3.11 rgettm function ........ 1.3.12 rgetui function ........ 1.3.13 rgetul function ........ 1.3.14 rgotofld function ...... 1.3.15 ristxtfld function ..... 1.3.16 risvalid function ...... 1.8.7 rnames function ........ 1.7.6 rnbgeti function ....... 1.3.17 rnbgetl function ....... 1.3.18 rnbgetui function ...... 1.3.19 rnbgetul function ...... 1.3.20 rngetc function ........ 1.3.21 rngetd function ........ 1.3.22 rngetf function ........ 1.3.23 rngeti function ........ 1.3.24 rngetl function ........ 1.3.25 rngets function ........ 1.3.26 rngett function ........ 1.3.27 rngettm function ....... 1.3.28 rngetui function ....... 1.3.29 rngetul function ....... 1.3.30 rnumfld function ....... 1.7.8 ropen function ........ 1.2.3 ROPEN_MAX macro ........ 1.1.3 rputc function ......... 1.4.5 rputd function ......... 1.4.6 rputf function ......... 1.4.7 rputi function ......... 1.4.8 rputl function ......... 1.4.9 rputrec function ....... 1.7.9 rputs function ......... 1.4.10 rputt function ......... 1.4.11 rputtm function ........ 1.4.12 rputui function ........ 1.4.13 rputul function ........ 1.4.14 rrecs function ......... 1.7.10 rrecno function ........ 1.7.11 rresetstr function ..... 1.7.12 rsetbegcolno function .. 1.7.7, 1.7.13 rsetbegyr .............. 1.7.14 rsetcxtno function ..... 1.8.8 rseterr function ....... 1.8.9 rseterrfn function ..... 1.8.10 rsetfldch function ..... 1.3.31 rsetfldpos function .... 1.7.15 rsetfldsiz function .... 1.2.4 rsetfldstr function .... 1.7.16 rsetrecsiz function .... 1.2.5 rsetrecstr function .... 1.7.17 rsettmfmt function ..... 1.3.32 rsettxtch function ..... 1.3.33 rsetwarn function ...... 1.9.2 rsetwarnfn function .... 1.9.3 rskipfld function ..... 1.3.34 rskipnfld function ..... 1.3.35 rstrerror function ..... 1.8.11 rstrwarning function ... 1.9.4 rwarning function ...... 1.9.5 rwarnstr function ...... 1.9.6